Why HTTP/2 (performance motivation)

On Node.js the previous default transport (node-fetch over HTTP/1.1) opens a new TCP + TLS connection per concurrent request — HTTP/1.1 can't multiplex, so a burst of N in-flight requests means up to N handshakes and, once the socket pool is saturated, requests queue waiting for a free connection. That connection setup and queueing lands squarely in the tail latency.

The SDK's node:http2 transport multiplexes many concurrent requests as streams over a small shared pool of connections: one handshake amortized across many requests, no per-request connection setup, and no pool-exhaustion queueing. Runloop SDK traffic is bursty and highly concurrent (agents firing many devbox operations in parallel), which is exactly the workload HTTP/2 multiplexing is built for. Bulk transfers stay at parity because the H2 session's flow-control window is sized so large streams aren't RTT-bound.

End-to-end benchmark (dev)

Measured against dev from this branch (Node v24), same client config with only the http2 flag flipped. Indicative single-run results from a shared environment — compare like-for-like, not as absolute targets.

Request handling under high concurrency (primary)

The SDK's own load harness — loadtest/loadtest.ts (from #798) — fires many devboxes.create calls concurrently at a deliberately nonexistent blueprint (bp_nonexistent_loadtest_00000). Every request fails fast server-side (all HTTP 400, zero devboxes created), which isolates client + server request handling from actual provisioning — i.e. purely "can the stack absorb a burst of requests at once." Run here at 2,000 concurrent requests (reduced from the harness default; the sandbox FD limit is 4096), http2 set explicitly per pass:

Under a 2,000-request burst, HTTP/1.1 (node-fetch) opens a socket per request and serializes behind connection setup + pool limits, so latency balloons into multi-second territory; HTTP/2 multiplexes the whole burst over a small connection pool and clears it in under a second. This is the workload the default flip is aimed at.

Concurrent lightweight reads (secondary)

A smaller micro-benchmark firing N concurrent devboxes.list({ limit: 1 }) reads (warmup excluded, 0 failures) — a lighter endpoint where server processing dominates the median, so the win shows in the tail:

Concurrent large downloads (throughput parity)

8 × 10 MB via downloadFile, md5-verified (exercises the H2 flow-control window):

Bulk throughput is at parity (slightly ahead here), with all payloads byte-identical — HTTP/2 is not a regression for large transfers.

Summary

Makes HTTP/2 the default transport on Node.js. The SDK's native node:http2 transport multiplexes many concurrent requests over a small shared pool of TLS connections instead of opening one connection per request. Previously HTTP/2 was opt-in (http2: true); this flips the default from false → true.

• Web / Deno / Bun: unaffected — the platform fetch already speaks HTTP/2, and the H2 shim is a no-op there.
• Custom fetch: always wins over http2.
• Opt out: http2: false selects the HTTP/1.1 node-fetch transport.

Transport resolution

httpAgent only applies to the HTTP/1.1 path — the H2 pool manages its own connections. To avoid silently changing behavior for existing users who pass an httpAgent, resolution is:

No existing httpAgent user is silently moved off HTTP/1.1: they get a one-time notice and can drop httpAgent to adopt H2 or pass http2: false to silence it.

Shared connection pool

All clients using the default transport share a single HTTP/2 pool, so short-lived clients (e.g. one per request) don't each open — and leak — their own H2 sessions. Explicit H2FetchOptions still get a dedicated pool, since that's deliberate tuning.

Transport correctness

Making H2 the default surfaced two behaviors of the transport that only mattered once non-opt-in clients used it, both fixed here:

• Response contract — the H2 fetch now returns a standard node-fetch Response, so .asResponse() satisfies instanceof Response like the HTTP/1.1 transport does. Streaming is preserved (the H2 body is consumed as a Node Readable).
• Process lifetime — idle pooled H2 sessions are unref'd (and ref'd only while a request is in flight), so a short Node script or test process exits normally instead of hanging on open sockets.

Code organization

The transport-selection logic and its one-time warnings live in a handwritten helper, src/lib/http2-transport.ts. The generated src/index.ts keeps only a one-line call-site hook, so regeneration stays clean.

Docs

Rewrote the README HTTP/2 transport section for H2-as-default and the http2: false opt-out, and corrected stale copy that still described the previous undici-based transport (it's native node:http2).

Release

Ships as a minor version bump; http2: false is the documented opt-out.

Test plan

• tsc --noEmit clean.
• Unit coverage for transport resolution: default→H2 with a shared pool, http2: false opt-out, dedicated pool for H2FetchOptions, and both one-time warnings.
• Full jest suite against the mock server: 880 passed, 6 skipped, including all tests/api-resources/** and the h2-transport suite; the process exits promptly.

🤖 Generated with Claude Code